home *** CD-ROM | disk | FTP | other *** search
/ Monster Media 1996 #15 / Monster Media Number 15 (Monster Media)(July 1996).ISO / win_utl2 / oh2b30d.zip / OHINDEX.TXT < prev   
Text File  |  1996-04-04  |  25KB  |  490 lines

  1.                       Copyright 1996, Hyperion Softword
  2.  
  3.                     *************************************
  4.                     *  Orpheus 2, beta release 2.00.30  *
  5.                     *************************************
  6.  
  7.                 Comments and queries to:  Hyperion Softword,
  8.                 535 Duvernay, Sherbrooke, QC J1L 1Y8, Canada
  9.                     tel/fax - 819-566-6296 (Rod Willmot)
  10.                        email - willmot@interlinx.qc.ca
  11.  
  12.  
  13. Contents of this file:  Purpose
  14.                         Usage
  15.                         Registration Requirements
  16.                         Project Requirements
  17.                         Memory and Disk Requirements
  18.                         Index Order
  19.                         Output File 1 - ALLWORDS.LOG
  20.                         Making an Exclusion List
  21.                         Making an Inclusion List
  22.                         Output File 2 - projname.IDX
  23.                         Reader Interface - Full-text Search
  24.                         Foreign Language Support
  25.  
  26. Last revised:  96-02-07
  27.  
  28.  
  29. PURPOSE:
  30. ========
  31.  
  32.     OHINDEX.EXE (The Orpheus Indexer) is a utility for indexing finished
  33.     documents created with Orpheus.  The resulting IDX file enables full-text
  34.     search in the Reader.  Note that the Indexer belongs to the feature set
  35.     of Orpheus Professional; see "Registration Requirements" below.
  36.  
  37.  
  38. USAGE:
  39. ======
  40.  
  41.         OHINDEX [/options] projname[.prj]
  42.  
  43.     The command-line must include the name of an existing project.  For
  44.     example, if the project is TEST (with a project file named TEST.PRJ),
  45.     a minimal command-line would be "OHINDEX test".  The project must be
  46.     in at least semi-finished state, with a valid NODELIST file in the
  47.     project directory; see "Project Requirements" below.
  48.  
  49.     Command-line switches:
  50.  
  51.       /a       - allow high-ascii characters that may be accented letters
  52.                  in a particular language; default is to treat them as spaces.
  53.                  See "Foreign Language Support" elsewhere in this document,
  54.                  and the following switch...
  55.       /e[filespec]
  56.                - use an exclusion list to specify words that you wish to
  57.                  leave out of the index.  If no filespec is given the program
  58.                  looks for EXCWORDS.TXT, first in the current directory, then
  59.                  in the project directory, and finally (if still not found)
  60.                  in the directory containing OHINDEX.EXE.  If you do give a
  61.                  filespec the file may be named whatever you please; the
  62.                  filespec can include a drive/path if different from the
  63.                  current directory.  See "Making an Exclusion List" below.
  64.        /h      - include hyphenated words; default is to treat a hyphen like
  65.                  a space, e.g. indexing "helter-skelter" as two words,
  66.                  "helter" and "skelter".  If you use the /h switch the index
  67.                  treats "helter-skelter" as one word (unless the hyphen is
  68.                  on a line-break).
  69.       /i[filespec]
  70.                - use an inclusion list to specify word *combinations* that
  71.                  you wish to be indexed.  If no filespec is given the program
  72.                  looks for INCWORDS.TXT, first in the current directory, then
  73.                  in the project directory, and finally (if still not found)
  74.                  in the directory containing OHINDEX.EXE.  If you do give a
  75.                  filespec the file may be named whatever you please; the
  76.                  filespec can include a drive/path if different from the
  77.                  current directory.  See "Making an Inclusion List" below.
  78.        /m[#]   - specify the minimum length of words to include; default
  79.                  is 3 (leaving out "he", "it", "to"...).  For example,
  80.                  /m4 sets a minimum word length of 4 characters.
  81.        /n      - include numbers (and words beginning with numbers); default
  82.                  is to leave them out.  For example, "2001" is normally
  83.                  left out, as is "21st".  When number-words are included, the
  84.                  characters ",-.:" (comma, hyphen, period, and colon) are
  85.                  permitted inside them; for example, "1,1", "2-2", "3.3",
  86.                  and "4:4" would all be indexed as words.
  87.        /q      - swiftly creates the ALLWORDS.LOG (see below), but does not
  88.                  store location data or build the final index (IDX file).
  89.                  Uses half or less memory than a normal run; see
  90.                  "Memory and Disk Requirements" below.
  91.       /s[filespec]
  92.                - strip accents from high-ascii characters according to a
  93.                  conversion list; default is to leave them alone.  Use of this
  94.                  switch automatically turns on the /a switch, but the reverse
  95.                  is not true.  Foreign-language users MUST make use of this
  96.                  feature to ensure correct sorting.  If no filespec is given
  97.                  we use a default conversion list.  See "Foreign Language
  98.                  Support" elsewhere in this document.
  99.       /t[#]    - specify the maximum number of location records to store for
  100.                  a single word; default is 6000.  The top limit for this
  101.                  number is 12000 due to memory demands in the Reader when
  102.                  Boolean search is provided.  See "Memory and Disk
  103.                  Requirements" below.
  104.  
  105.     Switches must be given before the project name, separated by a space,
  106.     and you can use "-" instead of "/".
  107.  
  108.     Examples:
  109.  
  110.         OHINDEX /q test
  111.             Performs a "quick" index of the TEST project, but only so far as
  112.             to make the ALLWORDS.LOG; it does not store location data or build
  113.             the final index.  Uses half or less memory than a normal run.
  114.             See "Memory and Disk Requirements" below.
  115.  
  116.         OHINDEX /m4 /n /s /a /e test
  117.             Sets a minimum word length of 4 characters; includes numbers
  118.             and hyphenated words (unless broken by a line-break); allows for
  119.             words containing accented (high-ascii) letters and strips the
  120.             accents according to the default conversion list; and uses the
  121.             exclusion list EXCWORDS.TXT, which may be in the current directory,
  122.             in the project directory, or in the directory containing the
  123.             Indexer.  Indexes the TEST project.
  124.  
  125.         OHINDEX /emylist.doc test.prj
  126.             Uses the exclusion list MYLIST.DOC in the current directory, and
  127.             indexes the TEST project.  Uses the default settings of 3 for
  128.             the minimum word length, leaves out numbers (and words beginning
  129.             with numbers), and breaks hyphenated words into multiple words.
  130.  
  131.  
  132. REGISTRATION REQUIREMENTS:
  133. ==========================
  134.  
  135.     OHINDEX.EXE is part of the Orpheus Professional feature set.  If you
  136.     are registered at the standard level, you are welcome to evaluate the
  137.     Indexer, but you may not distribute the IDX files with your finished works.
  138.     (If the Reader opens an IDX file with a work that was not assembled by a
  139.     user with an Orpheus Professional licence, it considers that work to have
  140.     been created with a *shareware* copy of the software, and displays the
  141.     "unregistered shareware" warning.)
  142.  
  143.     (If you do have an Orpheus Professional licence and the Indexer says
  144.     you don't, make sure it can find your OHREG.KEY file.  It should be in
  145.     the same directory as OHINDEX.EXE and your other Orpheus system files.)
  146.  
  147.     Please contact Hyperion Softword if you wish to upgrade to Orpheus
  148.     Professional.
  149.  
  150.  
  151. PROJECT REQUIREMENTS:
  152. =====================
  153.  
  154.     Before you can index a project it must pass through the first two stages
  155.     of project building:  compilation and link-verification.  (These are
  156.     performed through OH.EXE's Build Project dialog, on the Project Menu.)
  157.     To ensure that index data corresponds precisely to the contents of your
  158.     finished work, the Indexer works with the compiled versions of your cards,
  159.     which are stored in CMP files.  Just like the assembler (the final stage
  160.     of project building), it uses the NODELIST file to select only those
  161.     cards that belong in the finished work.  Only Text cards are indexed.
  162.  
  163.     Because the index gives the exact location of every instance of every
  164.     word that is included in the index, you have to do your part to keep
  165.     the index and HTX synchronized.  Whenever you update the HTX you should
  166.     regenerate the index immediately afterwards.
  167.  
  168.  
  169. MEMORY AND DISK REQUIREMENTS:
  170. =============================
  171.  
  172.     The amount of memory required to index a project depends on how many
  173.     unique words are included.  The amount of disk space required depends
  174.     on the total word count being included.  During processing a large
  175.     amount of temporary data is swapped to disk; since this can easily
  176.     amount to the total uncompiled size of your project, you will need
  177.     plenty of free disk space.
  178.  
  179.     An example:  at approximately half a megabyte of uncompiled text,
  180.     the online Help for Orpheus contains over 55000 words of 3 or more
  181.     characters.  Of that total the Indexer identifies some 3241 unique
  182.     words.  On a normal run (no exclusions or other switches) it uses
  183.     a maximum of about 128000 bytes of RAM.  On a "quick" run (with
  184.     the /q switch), memory use falls by more than half, to under 61000
  185.     bytes of RAM.
  186.  
  187.     The /q switch tells the Indexer not to store any data about the
  188.     locations of words.  This frees up a substantial amount of memory
  189.     and reduces disk use to a minimum.  If your project contains
  190.     tens of thousands of unique words, the Indexer may not be able to
  191.     get through to the end (on a normal run) without running out of memory.
  192.     If this happens, try again with the /q switch.  This will at least
  193.     generate an ALLWORDS.LOG which you can use to make an exclusion list;
  194.     both of these are discussed below.  Providing the Indexer with a
  195.     substantial exclusion list will free up a proportional amount of
  196.     memory, and of course will slim down your final IDX file.
  197.  
  198.     You can reduce the size of the final output file by using the /t switch
  199.     to set the maximum number of location records to store for a single word.
  200.     The default for this variable is 6000.  It could be argued that any
  201.     word occurring over a certain maximum is too common to demand a search
  202.     under any circumstances.  What that maximum is depends on the project and
  203.     your expectations; it could be as low as 500 or as high as 12000 -- the
  204.     highest currently permitted.
  205.  
  206.         The top limit is 12000 due to memory demands in the Reader.  With
  207.         searches on a single word the Reader uses the same very modest amount
  208.         of memory no matter how many records there are.  However, with
  209.         multi-word or Boolean searches (planned for future development),
  210.         memory use is exactly proportional to the number of records.
  211.  
  212.  
  213. INDEX ORDER:
  214. ============
  215.  
  216.     The index is alphabetically sorted.  However, if numbers are included,
  217.     such as "21st" or "2001", they are given first (in ascending order).  If
  218.     high-ascii characters are included and the /s switch isn't used, any words
  219.     that begin with an accented letter are given last (after the last letter
  220.     of the regular alphabet).  Since sorting is by ascii-value, words
  221.     beginning with accented characters may not be in the order expected for a
  222.     particular language.  Use of /s switch corrects this phenomenon (see
  223.     "Foreign Language Support").
  224.  
  225.  
  226. OUTPUT FILE 1 - ALLWORDS.LOG:
  227. =============================
  228.  
  229.     The first product of the Indexer is a file named ALLWORDS.LOG, which
  230.     is placed in the project directory of the project being indexed.  This
  231.     is a plain text file containing a complete list, in alphabetical order, of
  232.     the words included in the index.  Each word is given on a separate line,
  233.     followed by a space and a number; the number is the word's "hit count" --
  234.     how many times it was encountered.  You can view this file with any
  235.     text editor or file viewer, or even load it into OH.EXE.
  236.  
  237.     The ALLWORDS.LOG is generated for your use, not the Indexer's.  You may
  238.     delete it if you wish, but it does have an important purpose -- to
  239.     enable you to generate an exclusion list, discussed below.  When you use
  240.     the /q switch on the command line, the Indexer *only* makes ALLWORDS.LOG.
  241.  
  242.  
  243. MAKING AN EXCLUSION LIST:
  244. =========================
  245.  
  246.     While developing the Indexer I tested it on the online Help for Orpheus.
  247.     Here is a sample of the ALLWORDS.LOG from the preliminary output:
  248.  
  249.                             abandoned 1
  250.                             ability 16
  251.                             able 13
  252.                             abort 6
  253.                             aborting 3
  254.                             aborts 1
  255.                             absence 3
  256.                             absolutely 1
  257.  
  258.     Obviously, none of those words has anything to do with a significant
  259.     topic in Help.  Storing them in the index, with their location records,
  260.     would require some 300 bytes of dataspace; storing the word "would"
  261.     (with some 122 location records) would require over 600 bytes of
  262.     dataspace.  Multiply by thousands for popular words like "then" and
  263.     "there", and watch your disk fill up with useless data.
  264.  
  265.     The solution is to make an exclusion list:  a text file in the same
  266.     format as the ALLWORDS.LOG, listing all of the words that you do NOT
  267.     want in your index.  Please note the following specifications:
  268.  
  269.         * The exclusion list must give one word per line; anything after
  270.           the first word on a line will be ignored.  Therefore, you can
  271.           copy lines directly from the ALLWORDS.LOG into your list without
  272.           having to remove the numbers.
  273.  
  274.         * Lines beginning with ";" or "/" are ignored.
  275.  
  276.         * The exclusion list can use both uppercase and lowercase.
  277.  
  278.         * The exclusion list must be in strict alphabetical order, as in
  279.           ALLWORDS.LOG.  If you are including numbers but wish to exclude
  280.           specific numbers (or words beginning with numbers), give them
  281.           first and in ascending order.  If you are including high-ascii
  282.           characters but wish to exclude specific words beginning with
  283.           high-ascii characters, give them last.
  284.  
  285.         * If you are using accented characters (e.g. in French or Dutch)
  286.           and are using accent-stripping with the /s switch, the exclusion
  287.           list MUST NOT contain any accents.  This is because accent-stripping
  288.           is peformed just before the test for exclusion.  If you intend to
  289.           build your exclusion list on the basis of ALLWORDS.LOG, do so
  290.           with accent-stripping enabled right from the start, since the LOG
  291.           will then contain no accents.  If you obtain a word list from some
  292.           other source, you may need to use a word processor to convert the
  293.           accented characters if any.
  294.  
  295.         * The Indexer will only use your exclusion list if you tell it to,
  296.           with the /e switch on the command line.
  297.  
  298.         * The exclusion list may be as short as a single word, but cannot be
  299.           longer than 65535 bytes.  I may increase capacity if there is
  300.           demand for it.
  301.  
  302.     A simple way to create an exclusion list is to run the Indexer once on
  303.     your project (use the /q switch to do this quickly), then load the
  304.     resulting ALLWORDS.LOG in OH.EXE or any text editor, and do one of the
  305.     following:
  306.  
  307.           - either copy selected lines into a separate EXCWORDS.TXT file...
  308.           - or *delete* from the LOG whatever words you do want in the
  309.             index, leaving behind all those that you don't.  Be sure to
  310.             rename the resultant file EXCWORDS.TXT to prevent the Indexer
  311.             from overwriting it later.
  312.  
  313.     The default filename for the exclusion list is EXCWORDS.TXT.  If you
  314.     use the /e switch without a filespec, the Indexer looks for EXCWORDS.TXT
  315.     in the current directory; if the file is not there, it looks in the
  316.     project directory for the project being indexed; and if not there, it
  317.     looks in the directory containing OHINDEX.EXE (in case that is different).
  318.     If you do give a filespec the Indexer looks for exactly the file you
  319.     specify.
  320.  
  321.     Once you have created an exclusion list you can continue to extend it
  322.     for use with the same project or with other projects.  It doesn't matter
  323.     if the list contains words that are not even used by a project.  What
  324.     does matter is that the list be in strict sorted order as discussed above.
  325.     If the list falls out of order or if you are uncertain how to sort
  326.     accented characters, you can easily sort the file by using the DOS
  327.     SORT command.  (See DOS help on SORT.EXE for details.)
  328.  
  329.  
  330. MAKING AN INCLUSION LIST:
  331. =========================
  332.  
  333.     For special purposes you may wish to include word combinations in the
  334.     index.  This can be done with the aid of an inclusion list, using the
  335.     /i switch on the command-line together with a file named INCWORDS.TXT
  336.     (created by you with any text editor).  For example, in a legal work
  337.     references to articles of the law may take the form "Article 2" or
  338.     "Art. 2", and it would be useful to have the index list all occurrences
  339.     of "Art." or "Article" *together with* those numbers.  Somewhat
  340.     differently, a work on beverages might include references to drinks
  341.     whose names consist of more than one word, such as "Harvey Wallbanger".
  342.  
  343.     An inclusion list to handle these examples would go like this:
  344.  
  345.         "art. "+
  346.         "article "+
  347.         "harvey wallbanger"
  348.  
  349.     The rules are obvious:  the main part of the combination must be
  350.     enclosed in quotation marks.  In the case of "harvey wallbanger", that's
  351.     all there is.  In the other two cases, adding a "+" plus sign tells
  352.     the Indexer to add to the combination any additional characters UP TO
  353.     THE END OF THE WORD.  Since "art. " and "article " each end with a
  354.     space, this means that anything AFTER the space will be treated as
  355.     belonging to the same word.  Thus "Art. 2" will be included, as will
  356.     "Article Fifty-nine" and so on.
  357.  
  358.         NOTE:  In some cases you will need to add other switches to make
  359.         sure that everything is included as desired.  Adding the /h switch
  360.         ensures that hyphenated words are allowed.  Adding the /n switch
  361.         ensures that numbers are allowed, and that a number-word may include
  362.         such characters as "-,.:".  Thus, with the /n switch and the "art. "+
  363.         entry in the inclusion list, "Art. 2.20.17" would be indexed as
  364.         if it were a single word.
  365.  
  366.     Please note the following additional specifications:
  367.  
  368.         * The inclusion list must give one entry per line.  No leading
  369.           spaces are allowed, and the entry must be enclosed in quotation
  370.           marks, optionally followed by a "+" sign as discussed above.
  371.  
  372.         * Lines beginning with ";" or "/" are ignored.
  373.  
  374.         * The inclusion list can use both uppercase and lowercase; within
  375.           the IDX, all words are rendered in lowercase characters.
  376.  
  377.         * The inclusion list must be in strict alphabetical order, as in
  378.           ALLWORDS.LOG and the exclusion list.
  379.  
  380.         * If you are using accented characters (e.g. in French or Dutch)
  381.           and are using accent-stripping with the /s switch, the inclusion
  382.           list MUST NOT contain any accents.
  383.  
  384.         * The Indexer will only use your inclusion list if you tell it to,
  385.           with the /i switch on the command line.
  386.  
  387.         * The inclusion list may be as short as a single line, but may
  388.           not be longer than 12288 bytes.
  389.  
  390.     The default filename for the inclusion list is INCWORDS.TXT.  If you
  391.     use the /i switch without a filespec, the Indexer looks for INCWORDS.TXT
  392.     in the current directory; if the file is not there, it looks in the
  393.     project directory for the project being indexed; and if not there, it
  394.     looks in the directory containing OHINDEX.EXE (in case that is different).
  395.     If you do give a filespec the Indexer looks for exactly the file you
  396.     specify.
  397.  
  398.  
  399. OUTPUT FILE 2 - projname.IDX:
  400. =============================
  401.  
  402.     On conclusion of a normal run (without the /q switch), the Indexer
  403.     generates the final index to your project.  This file has the same
  404.     name as your project but with an extension of ".IDX".  The IDX file
  405.     can then be used by the Reader, as discussed below.  (Please note
  406.     that you may only distribute the IDX with the finished version of
  407.     your work if you are registered at the level of Orpheus Professional.
  408.     See "Registration Requirements" above.)
  409.  
  410.  
  411. READER INTERFACE - FULL-TEXT SEARCH:
  412. ====================================
  413.  
  414.     The Reader interface is illustrated by the Search dialog in online
  415.     Help.
  416.  
  417.  
  418. FOREIGN LANGUAGE SUPPORT:
  419. =========================
  420.  
  421.     The Indexer works by default in terms of the English language, which does
  422.     not use accented (high-ascii) characters.  You can modify this behavior
  423.     by using the /a or /s switch (or both) on the command line, as shown
  424.     under "Command-line switches" in the "Usage" section at the top of this
  425.     document.
  426.  
  427.     The /a switch turns on inclusion of high-ascii characters within words,
  428.     on the assumption that they may be accented letters.  (Only characters
  429.     that MIGHT be letters are so included; those that are linedraw characters
  430.     or other symbols on one or more of the code-pages that I have examined
  431.     are left out.)  Note that words containing high-ascii characters will not
  432.     be correctly sorted if only the /a switch is used.  Specifically, all
  433.     words beginning with a high-ascii character are grouped after the last
  434.     regular letter of the alphabet, "z".
  435.  
  436.     The /s switch corrects this problem by stripping the accents prior to
  437.     sorting.  (The /s switch automatically turns on the /a switch.)  Note
  438.     that to the computer there is no connection whatever between a given
  439.     low-ascii letter and its high-ascii accented version; with a different
  440.     code-page enabled, the high-ascii character may not even be a letter.
  441.     Therefore, conversion is performed according to a "strip list" consisting
  442.     of pairs of related characters:  a high-ascii accented character followed
  443.     by the regular letter of the alphabet to which it should be converted.
  444.     Here is the default striplist:
  445.  
  446.         ÇcüuéeâaäaàaåaçcêeëeèeïiîiìiÄaÅaÉeæeÆeôoöoòoûuùuÿyÖoÜuáaíióoúuñnÑn
  447.  
  448.     In other words, "Ç" will convert to "c", "ü" will convert to "u", and
  449.     so on.  You can provide your own striplist if you wish, as outlined
  450.     below.  There are two reasons for doing this:  one would be because
  451.     the default list does not include characters used in your language.
  452.     Another would be because your language uses only a few such characters,
  453.     and you will get much better performance with a shorter striplist.
  454.  
  455.     To make your own striplist, follow the example above, placing the entire
  456.     list on the first line of a text file.  The Indexer considers the list
  457.     to end at the first space or line-break if either of these occurs before
  458.     the end of the file.
  459.  
  460.         Please note that while the first character in each pair can be
  461.         whatever you like, the second must be a LOWERCASE letter of the
  462.         alphabet in order for the conversion to have the desired effect.  Do
  463.         NOT make a list like "ÇCüUéEâAäAàA", because it simply won't work.
  464.  
  465.     To tell the Indexer to use your striplist instead of the default, add
  466.     the name of the file to the /s switch on the command line, without any
  467.     intervening spaces, e.g.  "ohindex /sstripper.txt test" to index the
  468.     TEST project while using STRIPPER.TXT for character conversion.
  469.  
  470.     When accent-stripping is enabled, the final IDX file contains a copy of
  471.     the striplist used.  The same list is then applied to any input typed in
  472.     by the user, so that "cañon" will come out as "canon" and be correctly
  473.     located in the index.
  474.  
  475.     NOTE: certain languages may use letters that the Indexer excludes even
  476.     with the /a switch.  For users registered at the Orpheus Professional
  477.     level, I will be happy to extend the Indexer's intelligence; all I need
  478.     is a list of the desired ascii values or a photocopy of the code-page
  479.     listing from your DOS manual.  (This offer applies to languages based
  480.     on the Roman alphabet; I can't promise anything about Russian for
  481.     example.)  Code-pages currently supported include:
  482.  
  483.                         437    English
  484.                         850    Multilingual (Latin I)
  485.                         852    Slavic (Latin II)
  486.                         860    Portugal
  487.                         863    Canadian-French
  488.                         865    Nordic
  489.  
  490.